Providing Text or Pictures for Help Balloons
Use help balloons to provide the user with information that describes
or explains elements of your application. The information you supply
in help balloons should follow a few general guidelines in order to
provide the most useful information to the user. This section describes
these guidelines.
For examples of how your application should use help balloons,
observe the help balloons provided by the Finder, the TeachText
application, and system software.
Defining the Help Balloon Content
Use help balloons to explain parts of the interface of your application
that might confuse a new user or elements that could help a user
become an expert user. The information you provide in help balloons
should identify interface elements in your application or describe how
to use them. Each help balloon should answer at least one of these
questions:
• What is this? For example, when the user moves the cursor
to the item count in the upper-right corner of a Finder window,
the Finder displays a help balloon that reads “This is the number
of files or folders in this window.
• What does this do? For example, when the user moves the
cursor to the Find command in the Finder's File menu, the Finder displays a help balloon that reads “Finds and selects files
and folders with the characteristics you specify.
• What happens when I click this? For example, when the
user moves the cursor to the close box of a window, the
element (“Close box") and then explains “To close this window,
click here.
The content of help balloons should be short and easy to understand.
You should not include lengthy instructions or numbered steps in help
balloons. Use help balloons to clarify the meaning of objects in your
application-for example, tool symbols in palettes.
Use simple, clear language in the information you provide. Include
definitions in help balloons when appropriate.
You can use graphics or styled text in help balloons to illustrate the
effects of a command. For example, to demonstrate the Bold command
in a word-processing application, you might use styled text to show a
word in boldface.
You can provide separate help balloons for each state of a menu item
or dialog item. The help balloon that you provide for an enabled menu
item should explain the effect of choosing the item. The help balloon
that you provide for a dimmed menu item should explain why it is not
currently available, or, if more appropriate, how to make it available.
Complicated dialog boxes can often benefit from help balloons that
explain what's essential about the dialog box. You can use help balloons
to describe groups of controls rather than individual controls. For
example, if a dialog box has several distinct regions that contain radio
buttons or check boxes, you could provide a help balloon for each set of
radio buttons, rather than providing a separate balloon for each button.
If you use a function to customize standard dialog boxes, use as many
of the existing help balloons as possible. For example, if your
application uses any of the standard file dialog boxes and provides an
extra button, you can create a help balloon for the extra button, and
the
Help Manager continues to use the default help balloons for other elements of the dialog box.
To make localization easier, you should store the content of your help
balloons in resources separate from the help resources.
See Worldwide Software Overview and developing software for a worldwide market.
Using Clear, Concise Phrases
You can provide up to 255 characters of information using text
strings in help balloons. (You can use up to 32 KB if you use styled
text.) However, you should include only the most relevant information
in the help balloon. To determine what to provide, decide what
information would be most useful to a user. This information does not
usually give the object's name, which normally does not matter to the
user, but instead tells what the object is for and what the object does.
This information does matter to the user.
You might eventually translate your help content into other
languages, so try to keep the information as short as possible. When
translated, your help messages may require more words or longer
words-and therefore larger balloons and more screen space.
(Translated text is often 50 percent longer than the equivalent U.S.
English text.) Also avoid language or phrasing that might be colloquial,
offensive, or likely to lose its meaning when translated into an other
language.
If an item already has a commonly used name, or if it is a special case
of a larger category of objects, name it in the balloon. The Finder, for
example, displays the message "Drag the title bar to move the
window," since title bars and windows are commonly used names.
However, you do not need to name everything in your application just
so that you can refer to it in a help balloon. The tip of the help balloon
points to the subject of the help balloon. You can easily say "To apply
the style, click here," rather than "The Apply button activates the
Styles command. Click the button to activate the command.
For balloons that describe menu items, you can use sentence
fragments. The subject can be omitted because it is obvious from the
context. Using sentence fragments lets users assimilate the content of
the balloon more quickly because they have fewer words to read. For
example, the help balloon for the Open command could read "Opens the selected file" rather than "This command opens the selected file.
Using Active Constructions
Try to use short, active phrases in help balloons. Avoid passive
constructions. An active construction is more forceful because it
communicates how a subject (usually the user in this context)
performs an action. In the sentence "To turn the page, click here," the
implied "you" (that is, the user) is the subject, and "click" is the
action that the subject performs. Passive constructions show subjects
being acted upon rather than performing the action. For example, both
"page" and " button" are acted upon in their respective clauses in the
sentence "The page will be turned when this button is clicked.
Research suggests that in instructional materials it is better to
present the goal clause before the action clause to help readers quickly
recognize how the information meets their needs. Users are then able
to determine whether the content is relevant to what they want to do. A
goal might be "To turn the page," "To calculate the result," or "To
apply the style." For example, the message "To turn the page, click
here" starts with a goal statement and then describes the action
necessary to fulfill it; users find this more helpful than a purely
de scriptive message like "This button turns the page.
Using Parallel Structure
Use similar syntax for help balloons that describe similar objects.
For example, all help balloons that describe buttons should have the
same structure. In a style dialog box, you might provide these
messages for the buttons: "To see the style, click Apply," "To
implement the style, click OK," and "To do nothing to change the
previous style, click Cancel.
Users see help balloons provided by many different applications, so a
consistent approach within your application helps them to quickly
identify types of balloons and to develop realistic expectations about
their content.
Using Consistent Terminology
You should employ consistent terminology in all your help balloons.
Use language that users understand. Avoid introducing technical jargon
or computer terminology into help balloons. Follow the style and usage
standardized by Apple, in the Apple Publications Style Guide
(available through APDA) to make the most effective use of the
information and vocabulary with which users are already familiar.
Defining the Help Balloon Position
When you provide a help balloon, you specify its content, the tip of
the help balloon, and the variation code for its preferred position. The
tip of the help balloon should point to the object the help balloon
describes. You should specify the tip location and the variation code so
that the help balloon does not obscure the object you're providing help
for. In most cases, the tip of the help balloon should point to an edge of
the object you're providing help for.
You should also consider how the Help Manager re positions the balloon if the variation code places it off screen.
re positions the help balloon if necessary.